Skip to content

export: scoped erwin export of one subject area, with GUID preservation - #62

Merged
dbose merged 1 commit into
mainfrom
feat-erwin-scoped-export
Nov 1, 2026
Merged

dbose merged 1 commit into
mainfrom
feat-erwin-scoped-export

Conversation

@dbose

@dbose dbose commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner

Why

The erwin exporter always serialized the WHOLE model. The real workflow: import a large erwin mart (many subject areas), iterate on ONE subject area (SA1), export just that slice, and merge it back into the mart's SA1 as updates, not duplicates.

What

Three parts, built together.

Part C — GUID preservation (identity). The importer now stashes each erwin object's original GUID in a new optional erwin_id field (on LogicalEntity/Attribute/KeyGroup/Relationship/SubjectArea/Domain/Category; the entity GUID lives on LogicalEntity, since one erwin <Entity> splits into conceptual+logical). Export re-emits it via _oid(obj), so erwin matches/updates the object on re-import. A Modelith-authored object has no erwin_id → stable synthetic GUID → comes in as new (honored by erwin). Additive/optional: non-erwin models and existing tests are unaffected.

Why GUID, not name: the importer lowercases display names, which is irreversible for acronyms (USUBJID→usubjid→"Usubjid"). SDTM/clinical marts are acronym-heavy, so name-based matching would duplicate exactly the key columns. Only the preserved GUID matches exactly.

Part A — scope filter. emit_erwin(model, *, subject_area=) exports only that area's member entities in full. Unscoped export is byte-identical to before.

Part B — cross-SA FK stubs. A relationship from an in-scope entity to an entity OUTSIDE the area is kept, and the outside entity is emitted as a minimal stub (its real GUID + name + business key only) so the FK resolves — in erwin the neighbour auto-includes into the area's view.

Surfaces: mdl export erwin --subject-area/-s <name|id>; /api/export/erwin?subject_area=. Canvas Export-menu scoping deferred (CLI+API are the core).

Verified

On a 2-SA model with a genuine cross-SA FK: scoping to SA1 gave the SA1 entity in full, the shared dimension as a BK-only stub carrying its real GUID, and the FK retained — XSD-valid (xmllint), round-trips through the importer, 0 validate errors. 16 emitter tests + 3 CLI tests. Full suite 1034 passed, ruff clean.

Migration for an already-imported model (no new tooling)

The GUID only lands on a fresh import. For existing work: export current iteration to a scrap (mdl export mermaid) → upgrade → re-import the original erwin XML (GUIDs captured) → mdl import mermaid <scrap> --apply → mdl export erwin -s <SA>. Reuses existing --apply.

Workflow: import a big erwin mart, iterate on ONE subject area, export just that slice and
merge it back into the mart's SA as UPDATES (not duplicates).

Part C (identity, done first): the importer now preserves each erwin object's original GUID in
a new optional ir.py field erwin_id (on LogicalEntity/Attribute/KeyGroup/Relationship/
SubjectArea/Domain/Category; the entity GUID lives on LogicalEntity since one erwin <Entity>
splits into conceptual+logical). Additive/optional — non-erwin models and existing tests are
unaffected. Export's _oid(obj) re-emits erwin_id when present, so erwin matches the object;
a Modelith-authored object (no erwin_id) gets a stable synthetic GUID and comes in as NEW.
Why GUID not name: the importer lowercases display names, which is irreversible for acronyms
(USUBJID->usubjid->'Usubjid'), so name matching would duplicate SDTM key columns.

Part A+B (scope + stubs): emit_erwin(model, *, subject_area=) exports only that area's member
entities in full. A relationship from an in-scope entity to an outside one is KEPT, and the
outside entity is emitted as a minimal STUB (its real GUID + name + business key only) so the
FK resolves — in erwin the neighbour auto-includes in the area's view. Unscoped export is
byte-identical to before.

Surfaces: mdl export erwin --subject-area/-s <name|id>; /api/export/erwin?subject_area=.
(Canvas Export-menu scoping deferred — CLI+API are the core.)

Verified: scope to SA1 with a cross-SA FK -> SA1 entity full, the shared dimension as a
BK-only stub with its real GUID, the FK retained; XSD-valid + round-trips, 0 validate errors.
16 emit tests + 3 CLI tests. Full suite 1034 passed.
@dbose
dbose merged commit be47127 into main Nov 1, 2026
2 checks passed
dbose added a commit that referenced this pull request Nov 1, 2026
0.8.1 -> 0.8.2. Ships scoped erwin export (PR #62): mdl export erwin --subject-area / -s
exports one subject area's slice, keeps cross-SA FKs via stubs, and preserves the original
erwin GUID (new ir.py erwin_id) so a re-import updates the mart's objects instead of
duplicating them. Backward-compatible additions to the existing command.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant